Internal Study objects

Understanding the Study Descriptor Object

Every time a study is added to the chart a study descriptor object is created to track all its values. These default values can be inspected by your application, but should not be directly changed. Feel free to add your own custom values to the study description to track any additional pieces of information that may be required by your application.

Here is a screenshot in the debugger showing the rsi entry from the layout’s studies object.

Some of the more common properties of the study descriptor include:

Typical values within the study definition, which is used to create the descriptor, are discussed below.

Understanding the Study Definition

If a study descriptor represents an instance of a study, then a study definition would be its prototype. The study definition is an object which contains the default settings for a study, which will then be used to create the descriptor at the time the study is added to the chart.

Here is a typical study definition. It is for the “RAVI” study type, and it is a built-in study found within the CIQ.Studies.studyLibrary:

RAVI: {
	name: "RAVI",
	seriesFN: CIQ.Studies.displayRAVI,
	calculateFN: CIQ.Studies.calculatePriceOscillator,
	inputs: { Field: "field", "Moving Average Type": "vdma", "Short Cycle": 7, "Long Cycle": 65 },
	outputs: { "Increasing Bar": "#00DD00", "Decreasing Bar": "#FF0000" },
	parameters: {
		init: {
			studyOverZonesEnabled: true,
			studyOverBoughtValue: 3,
			studyOverBoughtColor: "auto",
			studyOverSoldValue: -3,
			studyOverSoldColor: "auto"
		}
	}
}

Below are some of the more common properties of the study definition.

name – Full name of the study. Optional, this name can be used when referencing a study in a menu or in a dialog, for ease of understanding. Our web-components use this value on the dropdown menu.

inputs – Default arguments passed into the study.

Inputs are used by the study to help compute its result.

The “inputs” field is not required, but if it is omitted, a default input of {"Period":14} will be created. This default exists since most studies utilize a period, and 14 is a typical setting. To force the study to have no inputs, set inputs to {}. An input can have any name as long as it is unique to the list of inputs, and does not use a reserved name (id, display).

Sidebar: Reserved input fields and Study Names

inputs.display - This reserved field is used to store a display-friendly name for the study instance. If not present, it is originally generated to be the same as inputs.id. It can also be modified at any time after the study is created. Note that it will not be translated to other languages when using CIQ.I18N.setLanguage.

parameters.display - Also note that if you still wish to have the study name built using the inputs in the key, but simply want to use a custom name instead of the type for the initial option, then set parameters.display. ie: if parameters.display is 'SAMPLE', the unique name would resemble "SAMPLE(param1,param2,param3,...)-X".

If both inputs.display and parameters.display are set, inputs.display will always take precedence.

You can directly set the display value on the study library entry for a new study, or extend an existing entry as follows:

CIQ.extend(CIQ.Studies.studyLibrary["rsi"],{inputs:{display:'YourCustomName'}});

An input can have one of the following value types:

• Number (integer or decimal)
• String
• Boolean
• Array of Strings

If the CIQ.Studies.DialogHelper object is used, there are a few shorthand values for inputs that can be utilized (as in the above example) to create an array of strings:

• Literal “field” – will expand to an array of available fields in the dataset
• Literal “ma” – will expand to an array of supported moving average types. Specifying a type of moving average (e.g., “vdma”) will do the same, but will default to the one specified. See “Adding a Moving Average Type” section below.

The unique id of a study instance is constructed using the inputs specified in this property.

calculateFN – Function which calculates the study results, also referred to as the “calculation function”.

This field is not strictly necessary, but omitting it indicates that the study does not perform any calculations because all resulting values are already present in the dataSet. This function will be discussed in more detail below.

outputs – Default colors and styles for each rendered study element.

*Set colors only

The colors can be expressed in either rgb, rgba, #hheexx or a web-friendly color name. Additionally, they can be set to “auto”, which allows the charting library itself to determine the appropriate color based on the chart theme. Outputs are not required, but if omitted, a default output of {"Result": "auto"} will be used.

outputs: { High: "#8cc176", Low: "#b82c0c" }

*Set colors and styles

This feature is only available for line studies.

Two additional parameters are allowed along with color: width and pattern.

• color is now its own field. All the rules in the previous section still apply.
• width takes a number and determines how thick the line will be displayed. Defaults to 1.
• pattern is the line dash pattern that will be displayed and takes one of the following values: solid, dotted, dashed. Defaults to solid.

outputs: {
	High: { color: "#8cc176", width: 3, pattern: "dashed" },
	Low: { color: "#b82c0c", width: 4, pattern: "dotted" }
}

Here is a screenshot showing the outputs as defined above.

parameters – Default additional fields affecting the study’s rendering.

Some default studies support the specification of additional parameters. But you can add here any settings you need for your study in addition to inputs and outputs.

There are two ways to use parameters:

1. Any parameters specified within parameters.init will be copied into the study descriptor (sd.parameters) when the study is added, and included in the CIQ.Studies.DialogHelper returned object to be used in the study dialog.

   Example:

       ma: {
           name: "Moving Average",
           overlay: true,
           calculateFN: CIQ.Studies.calculateMovingAverage,
           inputs: { Period: 50, Field: "field", Type: "ma", Offset: 0 },
           outputs: { MA: "#FF0000" },
           parameters: {
               init: {
                   panelName: "panel",
                   underlayEnabled: false,
                   yaxisDisplay: ["right", "left", "none", "shared"]
               }
           }
       }
   

2. Parameters not included in the parameters.init object, will remain in the sd.study.parameters object and can be used internally for your study logic, but will not be part of any menu.

The most common parameters supported deal with study zones for studies that render in a panel above or below the chart. A numerical value and color can be set for an over-bought and over-sold zone. The zones can also be enabled or disabled.

overlay – Whether the study will render over the chart or as a separate panel.

A value of true for this field indicates an overlay.

seriesFN – Function which renders the study results, also referred to as the “rendering function”.

Referencing a function here will allow a custom rendering of the study results on the chart. The results will appear either over the chart or in a separate panel, depending on the overlay property.

If this property is omitted, the results will be displayed as simple line plots, one for each field in the outputs property. If study zones are specified and overlay is not true, horizontal lines will be drawn at the zone levels and wherever results exceed the zone threshold the area between them will be shaded.

Note that the seriesFN function is called as part of the animation loop and should therefore be restricted to rendering computations. Any calculations of a study’s values which are dependent on quotefeed data should be put in the calculateFN function.

Convenience functions are available for the developer to use within seriesFN. Other properties are also available.

The built-in study definitions can be found in chartiq.js. These files should not be modified directly. Instead, use CIQ.extend() function to add or modify entries to the studyLibrary.

Reference Table of Study Definition Elements

Next steps

• Advanced Study Customization Tutorial.
• Creating New Studies.